home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / dviware / dvitovdu / vms / vduinterf.def < prev    next >
Text File  |  1990-10-01  |  12KB  |  241 lines
  1. DEFINITION MODULE VDUInterface;
  2.  
  3. (* Author:         Andrew Trevorrow
  4.    Implementation: University of Hamburg Modula-2 under VAX/VMS version 4
  5.    Date Started:   August, 1984
  6.  
  7.    Description:
  8.    This module provides the interface between DVItoVDU and the various
  9.    VDU-specific modules.  The implementation module will automatically
  10.    initialize all the generic VDU parameters and routines according to the
  11.    /VDU value extracted by DCLInterface.
  12.  
  13.    Revised:
  14.    October, 1984
  15.  - Removed ClearWindow since some VDUs have trouble doing this quickly.
  16.  - Added ResetVDU.
  17.    December, 1984
  18.  - Added LoadFont to allow a VDU to download given font if
  19.    possible, or to show characters at approximately the right
  20.    size (ShowChar no longer passes scaledsize in pixels).
  21.  - Added StartGraphics and StartText to make some VDUs more
  22.    efficient when drawing in window region.
  23.    January, 1984
  24.  - ShowPixel no longer needed.
  25.  - Stress that LoadFont, ShowChar and ShowRectangle must enter
  26.    and exit in graphics mode.
  27.    June, 1985
  28.  - No longer export GetVDUType.
  29.  - Coordinate pairs now shown as (h,v) instead of (v,h) to
  30.    be closer to (x,y) Cartesian coordinates.  Parameter order
  31.    in some routines has changed to reflect this.
  32.    September, 1985
  33.  - Improved LoadFont interface.
  34.  - Export TeXtoASCII array for use in ShowChar/Rectangle.
  35.    November, 1986
  36.  - TeXtoASCII array now 0C..377C because maxTeXchar is now 255.
  37.  
  38.    DVItoVDU assumes as little as possible about the capabilities of a VDU.
  39.    We should be able to implement any VDU that can:
  40.     - mix text and graphics on the screen (some VDUs make no distinction)
  41.     - erase all of the screen, or individual text lines
  42.     - move the cursor to any given screen pixel
  43.     - display a rectangular region of screen pixels (possibly just one).
  44.  
  45.    DVItoVDU's definition of a "screen pixel" is more precisely known as
  46.    an "addressable location".  Most graphic terminals use a coordinate scheme
  47.    in which there are more addressable locations than the number of physical
  48.    pixels making up the screen.  Such VDUs automatically scale given
  49.    addresses to actual physical pixels.
  50.  
  51.    After starting up, DVItoVDU breaks the screen into 2 parts:
  52.  
  53.    1. The DIALOGUE REGION will typically consist of the top 4 text lines on the
  54.       screen.  This region is used to display DVI and window status information,
  55.       various kinds of messages and the command prompt.  DVItoVDU assumes
  56.       text lines on the screen start at 1 and increase downwards.  The bottom
  57.       text line on the screen is given by the parameter bottoml (also the total
  58.       number of text lines).
  59.  
  60.    2. The WINDOW REGION is typically the remaining area of the screen and
  61.       is used to display some sort of representation of the current DVI page.
  62.       The user can move the window over any part of the current page,
  63.       or even completely outside the page edges (but only just).
  64.       The user can scale the page display by changing the width and height of
  65.       the window region; windowwd and windowht are the initial, unscaled
  66.       dimensions where one paper pixel equals one screen pixel.
  67.       When addressing screen pixels, DVItoVDU assumes the top left pixel
  68.       in the screen is at (0,0); horizontal coordinates increase to the right
  69.       and vertical coordinates increase down the screen.  The top left pixel
  70.       in the window region is at (windowh,windowv) in this coordinate scheme.
  71.       Specific VDU modules may have to do some translation to the actual
  72.       coordinate scheme used by the VDU.
  73.  
  74.    The following diagram illustrates the screen coordinate system used by
  75.    DVItoVDU and shows what the generic VDU parameters refer to.
  76.  
  77.                 --> h increases to the right
  78.    h,v=(0,0) *------------------------------------------------
  79.              |                               DVIstatusl      | top text line = 1
  80.        |     |              DIALOGUE REGION  windowstatusl   | (lines increase
  81.        V     |                               messagel        |  downwards)
  82.              |                               commandl        |
  83.        v     * (windowh,windowv) ----------------------------|   ---
  84.    increases |                                               |    |
  85.      down    |                                               |    |
  86.              |                                               |    |
  87.              |                                               |    |
  88.              |                WINDOW REGION                  | windowht
  89.              |         contains windowwd * windowht          |    |
  90.              |            addressable locations              |    |
  91.              |                                               |    |
  92.              |                               bottoml         |    |
  93.              -------------------------------------------------   ---
  94.  
  95.              |------------------ windowwd -------------------|
  96. *)
  97.  
  98. VAR
  99.    (* DVItoVDU treats these INTEGER variables as read-only parameters:        *)
  100.  
  101.    DVIstatusl,     (* DVI status line                                         *)
  102.    windowstatusl,  (* window status line                                      *)
  103.    messagel,       (* message line                                            *)
  104.    commandl,       (* command line                                            *)
  105.    bottoml,        (* bottom line; also number of text lines in screen        *)
  106.    windowh,        (* horizontal coord for window's top left screen pixel     *)
  107.    windowv,        (* vertical coord for window's top left screen pixel       *)
  108.    windowwd,       (* width of window in screen pixels                        *)
  109.    windowht        (* height of window in screen pixels                       *)
  110.       : INTEGER;
  111.  
  112.    TeXtoASCII : ARRAY [0C..377C] OF CHAR;
  113.    (* TeXtoASCII is an array of characters that can be used in a specific
  114.       ShowChar or ShowRectangle routine to map the given TeX character into
  115.       a similar looking ASCII character.
  116.  
  117.       index       (= TeX char)            -->  ASCII char (= TeXtoASCII[index])
  118.  
  119.       0C..12C     Greek letters           -->  all ?
  120.       13C..17C    ligatures               -->  all ?
  121.       20C, 21C    dotless i and j         -->  i and j
  122.       22C, 23C    grave and acute         -->  ` and '
  123.       24C..27C    other high accents      -->  all ~
  124.       30C         cedilla                 -->  ,
  125.       31C..40C    diphthongs and foreigns -->  all ?
  126.       41C..133C   !../,0..9,:..@,A..Z,[   -->  same as index
  127.       134C        opening double quote    -->  "
  128.       135C        ]                       -->  ]
  129.       136C, 137C  hat and dot accents     -->  both ^
  130.       140C..172C  `,a..z                  -->  same as index
  131.       173C, 174C  en dash and em dash     -->  both -
  132.       175C..177C  more high accents       -->  all ~
  133.       200C..377C  the rest                -->  all ?
  134.  
  135.       There are a few important features of the above mapping:
  136.        - The upper bound of 377C matches DVIReader's maxTeXchar value of 255.
  137.        - The TeX char is assumed to come from a text font, so characters from
  138.          non-text fonts (e.g., math and symbol fonts) will appear incorrect.
  139.        - We use ? as a catch-all for most of the TeX chars that have no
  140.          similar ASCII equivalent.  This allows specific ShowChar routines to
  141.          efficiently detect such cases and simulate ligatures, etc.
  142.        - Characters 74C and 76C are an upside down exclamation and question
  143.          mark in a TeX text font, but we map them to their equivalent
  144.          ASCII positions (< and >) since they are much more likely to occur
  145.          as the corresponding characters from a math or typewriter font.
  146.    *)
  147.  
  148.    (* PROCEDURE variables:
  149.       DVItoVDU does not assume anything about the new cursor position
  150.       after calling any of these routines (except MoveToTextLine of course).
  151.       Some specific VDU routines may be able to take advantage of the following
  152.       features:
  153.       - MoveToTextLine, ClearTextLine, ClearScreen and ResetVDU are only called
  154.         after a StartText call (i.e., when DVItoVDU is in "text mode").
  155.       - LoadFont, ShowChar and ShowRectangle are only called after a
  156.         StartGraphics call (i.e., when DVItoVDU is in "graphics mode").
  157.       - The sequence of ShowChar calls is defined by DVIReader: for each font,
  158.         characters will be shown in an essentially left-right, top-down manner.
  159.         Since the reference points of most characters in a line will have
  160.         the same vertical coordinate, some ShowChar implementations can reduce
  161.         the number of output bytes needed to update the screen position from one
  162.         character to the next.  (See the ANSIVDU implementation for example.)
  163.    *)
  164.  
  165.    StartText : PROC;
  166.    (* DVItoVDU calls this routine before displaying text in the dialogue region.
  167.       Some VDUs may need to get out of graphics mode and enter text mode.
  168.    *)
  169.  
  170.    MoveToTextLine : PROCEDURE (CARDINAL);
  171.    (* Move cursor to start of given text line. *)
  172.  
  173.    ClearTextLine : PROCEDURE (CARDINAL);
  174.    (* Erase given text line. *)
  175.  
  176.    ClearScreen : PROC;
  177.    (* Erase entire screen. *)
  178.  
  179.    StartGraphics : PROC;
  180.    (* DVItoVDU calls this routine before drawing in the window region.
  181.       Some VDUs may need to get out of text mode and enter graphics mode.
  182.    *)
  183.  
  184.    LoadFont : PROCEDURE (ARRAY OF CHAR, CARDINAL, REAL,      REAL,   REAL);
  185.                         (* fontspec,    fontsize, mag/1000,  hscale, vscale *)
  186.    (* DVItoVDU calls this routine just before displaying all the characters
  187.       for the given font.  The information passed in can be used by later
  188.       ShowChar calls.
  189.       It is anticipated that a bit-mapped graphics terminal may be able to
  190.       use this routine to download the given PXL file, scale the characters to
  191.       the right size, and produce a Terse display (via ShowChar calls) much
  192.       faster and almost as accurate as a Full display.
  193.       At the moment, some VDUs only use the given fontsize (the TeX font's
  194.       scaledsize converted into unscaled paper pixels) along with the mag,
  195.       hscale and vscale values to select an appropriate hardware "font" for
  196.       use in later ShowChar calls.
  197.    *)
  198.  
  199.    ShowChar : PROCEDURE (CARDINAL, CARDINAL, CHAR);
  200.                         (* h,      v,        char *)
  201.    (* Show the given character from the last font loaded.
  202.       (h,v) is the screen pixel representing the char's TeX reference point.
  203.       (Note that v coordinates are normally lined up along the baseline.)
  204.       DVItoVDU only calls this routine during a Terse display and guarantees
  205.       that (h,v) is somewhere in the window region.  It is up to the specific
  206.       VDU routine to decide how to handle characters too close to the screen
  207.       edge.  (The right edge is usually the most crucial one because (h,v)
  208.       is normally at the bottom left corner of the character, and the top of
  209.       the screen is normally well above the top of the window region.
  210.       Note that it is better to show something rather than nothing at all in
  211.       cases where part or all of the character is invisible.)
  212.       Most of the VDUs currently implemented assume the character is from a
  213.       TeX text font and map it into a suitable ASCII character using the
  214.       TeXtoASCII conversion array.
  215.    *)
  216.  
  217.    ShowRectangle : PROCEDURE (CARDINAL, CARDINAL, CARDINAL, CARDINAL, CHAR);
  218.                              (* h,      v,        width,    height,   char *)
  219.    (* Show a rectangular region of black pixels.
  220.       (h,v) is the TOP LEFT screen pixel in the rectangle.  The width and height
  221.       of the rectangle are also given in screen pixels (both > 0).
  222.       DVItoVDU guarantees that (h,v) is somewhere in the window region and that
  223.       the entire rectangle is visible.
  224.       Non-graphic VDUs may wish to use the given char as a "black pixel".
  225.       DVItoVDU uses this routine to display:
  226.        - all visible paper edges (char = '.')
  227.        - all visible rules (char = '*')
  228.        - the visible edges of a character box in a Box display (char = '*')
  229.        - the visible horizontal lines making up a character in a Full display
  230.          (char is the appropriate TeX character).
  231.       Most rectangles generated by DVItoVDU will be short horizontal lines
  232.       with a height of 1 pixel.
  233.    *)
  234.  
  235.    ResetVDU : PROC;
  236.    (* Some VDUs may need to be reset to a known state.
  237.       DVItoVDU calls this routine just before halting.
  238.    *)
  239.  
  240. END VDUInterface.
  241.